package cn.song.freight.service;

import cn.song.freight.domain.dto.OperationLogAddDTO;
import cn.song.freight.domain.dto.OperationLogQueryDTO;
import cn.song.freight.domain.entity.OperationLogDO;
import cn.song.freight.domain.result.PageUtils;
import cn.song.freight.domain.vo.OperationLogStatisticsVO;
import cn.song.freight.domain.vo.OperationStatisticsVO;
import cn.song.freight.domain.vo.OperatorStatisticsVO;
import com.baomidou.mybatisplus.extension.service.IService;

import java.util.List;

/**
 * 操作日志服务接口
 * <pre>
 * 该服务实现提供系统的操作日志管理功能，支持操作日志的记录、查询和统计分析，
 * 为系统提供完整的操作审计和追踪功能。
 *
 * 核心功能：
 * - 操作日志的自动记录和手动记录
 * - 支持多条件组合查询和分页查询
 * - 提供操作统计分析功能
 * - 历史日志清理和管理
 *
 * 日志记录内容：
 * 1. 基本信息：操作人、操作时间、操作类型、模块类型
 * 2. 业务信息：业务ID、业务名称、操作描述
 * 3. 数据变更：操作前数据、操作后数据、变更字段
 * 4. 请求信息：请求参数、请求方法、请求URL、IP地址
 * 5. 执行信息：执行耗时、操作状态、错误信息
 *
 * @author SongRenShuo
 * @version 1.0.0
 * @since 2025-08-29
 */
public interface OperationLogService extends IService<OperationLogDO> {

    /**
     * 记录操作日志
     * <pre>
     * 该方法实现操作日志的记录功能，接收操作日志信息并保存到数据库。
     * 通常由AOP切面或手动调用来记录系统操作。
     * 会自动设置操作时间为当前时间。
     *
     * @param addDTO 操作日志添加数据传输对象，包含日志的基本信息
     * @return 记录结果，true表示记录成功，false表示记录失败
     */
    Boolean recordOperationLog(OperationLogAddDTO addDTO);

    /**
     * 批量记录操作日志
     * <pre>
     * 该方法实现批量操作日志的记录功能，用于记录一次操作中涉及多个业务实体的情况。
     * 所有日志记录共享相同的链路追踪ID，便于关联查询。
     *
     * @param addDTOList 操作日志添加数据传输对象列表
     * @return 记录结果，true表示全部记录成功，false表示有记录失败
     */
    Boolean batchRecordOperationLog(List<OperationLogAddDTO> addDTOList);

    /**
     * 查询操作日志列表（分页）
     * <pre>
     * 该方法实现操作日志的条件查询功能，支持按模块类型、操作类型、操作人、
     * 业务ID、时间范围等多条件组合查询，查询结果按操作时间倒序排列。
     *
     * @param queryDTO 操作日志查询数据传输对象，包含查询条件和分页参数
     * @return 分页的操作日志列表
     */
    PageUtils<OperationLogDO> listOperationLogs(OperationLogQueryDTO queryDTO);

    /**
     * 根据链路追踪ID查询相关的所有操作日志
     * <pre>
     * 该方法根据链路追踪ID查询同一次操作中的所有日志记录，
     * 用于追踪完整的操作链路和业务流程。
     *
     * @param traceId 链路追踪ID
     * @return 相关的操作日志列表
     */
    List<OperationLogDO> listOperationLogsByTraceId(String traceId);

    /**
     * 查询操作统计信息
     * <pre>
     * 该方法查询系统的操作统计信息，包括各模块和操作类型的统计数据，
     * 用于系统监控和运营分析。默认统计最近7天的数据。
     *
     * @return 操作统计信息列表，包含模块类型、操作类型、操作次数等
     */
    List<OperationStatisticsVO> getOperationStatistics();

    /**
     * 查询最近的操作日志
     * <pre>
     * 该方法查询系统最近的操作日志，用于首页展示或快速查看最新操作。
     * 按操作时间倒序排列。
     *
     * @param limit 查询数量限制，默认20条
     * @return 最近的操作日志列表
     */
    List<OperationLogDO> getRecentOperations(Integer limit);

    /**
     * 根据操作人统计操作次数
     * <pre>
     * 该方法统计指定天数内各操作人的操作次数，
     * 用于分析用户活跃度和操作行为。
     *
     * @param days 统计天数，默认7天
     * @return 操作人统计信息列表
     */
    List<OperatorStatisticsVO> getOperationCountByOperator(Integer days);

    /**
     * 清理历史操作日志
     * <pre>
     * 该方法清理指定天数之前的历史操作日志，用于控制数据库存储空间。
     * 建议定期执行此操作，保留90-180天的日志数据即可。
     *
     * @param days 保留天数，删除该天数之前的日志
     * @return 清理的日志记录数
     */
    Integer cleanHistoryLogs(Integer days);

    /**
     * 根据业务ID查询相关操作日志
     * <pre>
     * 该方法根据业务ID查询相关的操作日志，用于追踪特定业务数据的操作历史。
     * 支持单个业务ID或批量业务ID查询。
     *
     * @param businessId 业务ID，支持单个ID或逗号分隔的多个ID
     * @param moduleType 模块类型，可选参数用于缩小查询范围
     * @return 相关的操作日志列表
     */
    List<OperationLogDO> listOperationLogsByBusinessId(String businessId, String moduleType);

    /**
     * 根据主键ID查询操作日志详情
     * <pre>
     * 该方法根据主键ID查询单条操作日志详情，用于查看具体操作的详细信息。
     * 包括操作前数据、操作后数据、响应结果等。
     *
     * @param id 操作日志主键ID
     * @return 操作日志详情
     */
    OperationLogDO getOperationLogById(Long id);

    /**
     * 查询详细统计信息
     * <pre>
     * 该方法查询系统的详细统计信息，包括：
     * - 今日操作数：今天的操作数量
     * - 成功操作数：全部成功的操作数量
     * - 失败操作数：全部失败的操作数量
     * - 总操作数：系统全部操作数量
     *
     * @return 详细统计信息
     */
    OperationLogStatisticsVO getDetailedStatistics();
}
